---
title: Server APIs
---

LiveKit has built-in APIs that lets you to manage rooms, update and moderate participants. These APIs are designed to be used by your backend.

Room APIs are built on top of [Twirp](https://twitchtv.github.io/twirp/docs/intro.html), and differ from a traditional REST interface. Arguments are passed via POSTing JSON body to the endpoints. The APIs are available at `/twirp/livekit.RoomService/<MethodName>`. For example, ListRooms would be `/twirp/livekit.RoomService/ListRooms`

Room APIs are fully distributed across multiple nodes. Each instance is capable of fulfilling requests about any room or participant.

### Authorization header

All of the APIs require a signed access token. The token should be set in HTTP headers as

```
Authorization: Bearer <token>
```

Our [server sdks](/references/server-sdks) will include the authentication header automatically.

### Post body

Twirp expects each request to be a HTTP POST. The body of the request should be
a JSON object (`application/json`) containing parameters specific to each request. For requests
that takes no parameters, an empty `{}` body should be used.

## APIs

### CreateRoom

Creates a room with settings. Requires `roomCreate` permission.
This method is optional; rooms are created automatically when clients connect to them for the first time.

| Parameter        | Type   | Description                                             |
| :--------------- | :----- | :------------------------------------------------------ |
| name             | string | name of the room                                        |
| empty_timeout    | uint32 | number of seconds to keep the room open if no one joins |
| max_participants | uint32 | limit number of participants that can be in a room      |

Returns [Room](#room)

### ListRooms

List rooms that are active on the server. Requires `roomList` permission.

Returns List<[Room](#room)>

### DeleteRoom

Deletes an existing room by name or id. Requires `roomCreate` permission.
DeleteRoom will disconnect all participants that are currently in the room.

| Parameter | Type   | Description      |
| :-------- | :----- | :--------------- |
| room      | string | name of the room |

### ListParticipants

Lists participants in a room, Requires `roomAdmin`

| Parameter | Type   | Description      |
| :-------- | :----- | :--------------- |
| room      | string | name of the room |

Returns List<[ParticipantInfo](#participantinfo)>

### GetParticipant

Gets information on a specific participant, Requires `roomAdmin`

| Parameter | Type   | Description                 |
| :-------- | :----- | :-------------------------- |
| room      | string | name of the room            |
| identity  | string | identity of the participant |

Returns [ParticipantInfo](#participantinfo)

### RemoveParticipant

Removes a participant from room. Requires `roomAdmin`

| Parameter | Type   | Description                 |
| :-------- | :----- | :-------------------------- |
| room      | string | name of the room            |
| identity  | string | identity of the participant |

### MutePublishedTrack

Mute/unmute a participant's track. Requires `roomAdmin`

| Parameter | Type   | Description                          |
| :-------- | :----- | :----------------------------------- |
| room      | string | name of the room                     |
| identity  | string |                                      |
| track_sid | string | sid of the track to mute             |
| muted     | bool   | set to true to mute, false to unmute |

### UpdateParticipant

Update participant metadata, will cause updates to be broadcasted to everyone in the room. Requires `roomAdmin`

| Parameter  | Type                                            | Description                                        |
| :--------- | :---------------------------------------------- | :------------------------------------------------- |
| room       | string                                          |                                                    |
| identity   | string                                          |                                                    |
| metadata   | string                                          | metadata to update. skipping updates if left empty |
| permission | [ParticipantPermission](#participantpermission) | set to update the participant&#39;s permissions    |

### UpdateSubscriptions

Subscribes or unsubscribe a participant from tracks. Requires `roomAdmin`.

As an admin, you can subscribe a participant to a track even if they do not have `canSubscribe` permission.

| Parameter  | Type           | Description                                                |
| :--------- | :------------- | :--------------------------------------------------------- |
| room       | string         |                                                            |
| identity   | string         |                                                            |
| track_sids | List<[string]> | list of sids of tracks                                     |
| subscribe  | bool           | set to true to subscribe, false to unsubscribe from tracks |

### UpdateRoomMetadata

Update room level metadata. Requires `roomAdmin`

This API allows you to attach user-defined metadata to a room. Changes to metadata will be broadcasted to all participants in the room.

| Parameter | Type   | Description                             |
| :-------- | :----- | :-------------------------------------- |
| room      | string |                                         |
| metadata  | string | user-provided payload opaque to LiveKit |

### SendData

Sends data messages to participants, triggering `onDataReceived` event on clients.

| Parameter        | Type           | Description                                                            |
| :--------------- | :------------- | :--------------------------------------------------------------------- |
| room             | string         |                                                                        |
| data             | bytes          |                                                                        |
| kind             | enum           | reliable or lossy                                                      |
| destination_sids | List<[string]> | list of participant sids to send to, sends to everyone when left blank |

## Types

### Room

| Field            | Type   |
| :--------------- | :----- |
| sid              | string |
| name             | string |
| empty_timeout    | string |
| max_participants | string |
| creation_time    | string |
| turn_password    | string |

### ParticipantInfo

| Field     | Type                          | Description                            |
| :-------- | :---------------------------- | :------------------------------------- |
| sid       | string                        | server generated identifier            |
| identity  | string                        | client provided identity               |
| state     | TrackInfo_State               |                                        |
| tracks    | List<[TrackInfo](#trackinfo)> | tracks published by participant        |
| metadata  | string                        |                                        |
| joined_at | int64                         | timestamp when participant joined room |

### TrackInfo

| Field     | Type      | Description                                   |
| :-------- | :-------- | :-------------------------------------------- |
| sid       | string    | server generated identifier                   |
| type      | TrackType | audio or video                                |
| name      | string    | name given at publish time                    |
| muted     | bool      | true if track has been muted by the publisher |
| width     | uint32    | original width of video (unset for audio)     |
| height    | uint32    | original height of video (unset for audio)    |
| simulcast | bool      | true if track is simulcasted                  |

### ParticipantPermission

| Field            | Type | Description                                                |
| :--------------- | :--- | :--------------------------------------------------------- |
| can_subscribe    | bool | allow participant to subscribe to other tracks in the room |
| can_publish      | bool | allow participant to publish new tracks to room            |
| can_publish_data | bool | allow participant to publish data to room                  |
